Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Unicode Converter Functions

Converting From Unicode /

ChangeUnicodeToTextInfo

Changes the mapping information contained in the specified Unicode converter object used to convert Unicode text to a non-Unicode encoding.

pascal OSStatus ChangeUnicodeToTextInfo (
      UnicodeToTextInfo ioUnicodeToTextInfo,
      ConstUnicodeMappingPtr iUnicodeMapping);

ioUnicodeToTextInfo

The Unicode converter object of type UnicodeToTextInfo (page 120) to be modified. You use the function CreateUnicodeToTextInfo (page 135) or CreateUnicodeToTextInfoByEncoding (page 136) to obtain a Unicode converter object of this type.

iUnicodeMapping

The structure of type UnicodeMapping (page 118) to be used. This is the new mapping that replaces the existing mapping in the Unicode converter object.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference."

DISCUSSION

The ChangeUnicodeToTextInfo function allows you to provide new mapping information for converting text from Unicode to a non-Unicode encoding. The function replaces the mapping table information that currently exists in the specified Unicode converter object with the information contained in the new Unicode mapping structure you provide.

ChangeUnicodeToTextInfo resets the Unicode converter object's fields as necessary. However, it does not initialize or reset the conversion state maintained by the Unicode converter object.

This function is especially useful for converting a string from Unicode if the Unicode string contains characters that require multiple destination encodings and you know the next destination encoding.

For example, you can change the other (destination) encoding of the Unicode mapping structure pointed to by the iUnicodeMapping parameter before you call the function ConvertFromUnicodeToText (page 139) to convert the next character or sequence of characters that require a different destination encoding.

In addition to various resource errors, the function can return the following result codes:

• paramErr
The Unicode converter object you supplied is invalid.
• kTextUnsupportedEncodingErr
One of the encodings specified by the Unicode mapping structure you supplied is not currently supported.
• kTECMissingTableErr
A resource associated with one of the encodings is missing.
• kTECTableChecksumErr
A resource has an invalid checksum, indicating that it has become corrupted.

If an error is returned, the Unicode converter object is invalid.